Summary

• Make standalone wait return exit code 11 (WAIT_TIMEOUT) when a wait result times out.
• Preserve the current success envelope shape for timeout results so automation can still inspect result.timedOut, matched, and capturedAtSeq.
• Add/update unit and integration coverage for render waits plus legacy --idle-ms / --exit waits.
• Update docs/USAGE.md and the README command-surface note for the new public CLI contract.

Closes #151.

User-facing behavior

A timed-out standalone wait now exits non-zero while still emitting an ok: true result envelope:

text_timeout_exit=11
text_timeout_envelope={"ok":true,"timedOut":true,"matched":false}

exit_timeout_exit=11
exit_timeout_envelope={"ok":true,"timedOut":true}

This makes shell composition fail closed:

agent-tty wait "$SID" --text ready --timeout 30000 --json && next-step

Validation

npm run format
npm run format:check
npm run lint
npm run typecheck
npm run test -- test/unit/commands/wait.test.ts test/integration/wait-render.test.ts test/integration/batch.test.ts test/unit/cli/exitCodes.test.ts test/unit/batch/executor.test.ts
npm run test -- test/integration/io-loop.test.ts test/integration/screen-hash.test.ts test/integration/wait-render.test.ts test/unit/commands/wait.test.ts
npm run test:integration
mise run ci

mise run ci was run before the initial commit and again after rebasing on origin/main; after the first PR CI surfaced stale integration expectations, the affected tests and the full integration suite were run locally before updating the PR branch.

Dogfooding

Used an isolated absolute AGENT_TTY_HOME and npx tsx src/cli/main.ts to create a live session, verify a successful render wait still exits 0, and verify standalone render and --exit timeouts now exit 11 while preserving success envelopes.

No visual UI changed; no screenshots or videos are included.

Generated with mux • Model: openai:gpt-5.5 • Thinking: xhigh